<!doctype html>
<html class="default no-js">
<head>
	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<title>@aws/dynamodb-batch-iterator</title>
	<meta name="description" content="">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
	<div class="tsd-page-toolbar">
		<div class="container">
			<div class="table-wrap">
				<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
					<div class="field">
						<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
						<input id="tsd-search-field" type="text" />
					</div>
					<ul class="results">
						<li class="state loading">Preparing search index...</li>
						<li class="state failure">The search index is not available</li>
					</ul>
					<a href="index.html" class="title">@aws/dynamodb-batch-iterator</a>
				</div>
				<div class="table-cell" id="tsd-widgets">
					<div id="tsd-filter">
						<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
						<div class="tsd-filter-group">
							<div class="tsd-select" id="tsd-filter-visibility">
								<span class="tsd-select-label">All</span>
								<ul class="tsd-select-list">
									<li data-value="public">Public</li>
									<li data-value="protected">Public/Protected</li>
									<li data-value="private" class="selected">All</li>
								</ul>
							</div>
							<input type="checkbox" id="tsd-filter-inherited" checked />
							<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
							<input type="checkbox" id="tsd-filter-externals" checked />
							<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
						</div>
					</div>
					<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
				</div>
			</div>
		</div>
	</div>
	<div class="tsd-page-title">
		<div class="container">
			<ul class="tsd-breadcrumb">
				<li>
					<a href="globals.html">Globals</a>
				</li>
			</ul>
			<h1> @aws/dynamodb-batch-iterator</h1>
		</div>
	</div>
</header>
<div class="container container-main">
	<div class="row">
		<div class="col-8 col-content">
			<div class="tsd-panel tsd-typography">
				<h1 id="amazon-dynamodb-batch-iteration">Amazon DynamoDB Batch Iteration</h1>
				<p><a href="http://aws.amazon.com/apache-2-0/"><img src="https://img.shields.io/github/license/awslabs/dynamodb-data-mapper-js.svg?style=flat" alt="Apache 2 License"></a></p>
				<p>This library provides utilities for automatically submitting arbitrarily-sized
					batches of reads and writes to DynamoDB using well-formed <code>BatchGetItem</code> and
					<code>BatchWriteItem</code> operations, respectively. Partial successes (i.e.,
					<code>BatchGetItem</code> operations that return some responses and some unprocessed keys
					or <code>BatchWriteItem</code> operations that return some unprocessed items) will retry
				the unprocessed items automatically using exponential backoff.</p>
				<h2 id="getting-started">Getting started</h2>
				<h3 id="reading-batches-of-items">Reading batches of items</h3>
				<p>Create a <code>BatchGet</code> object, supplying an instantiated DynamoDB client from the
					AWS SDK for JavaScript and an iterable of keys that you wish to retrieve. The
					iterable may be synchronous (such as an array) or asynchronous (such as an
					object stream wrapped with <a href="https://github.com/calvinmetcalf/async-iter-stream">async-iter-stream</a>&#39;s
				<code>wrap</code> method).</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> { BatchGet } <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-batch-iterator'</span>;
<span class="hljs-keyword">import</span> DynamoDB = <span class="hljs-built_in">require</span>(<span class="hljs-string">'aws-sdk/clients/dynamodb'</span>);

<span class="hljs-keyword">const</span> dynamoDb = <span class="hljs-keyword">new</span> DynamoDB({region: <span class="hljs-string">'us-west-2'</span>});
<span class="hljs-keyword">const</span> keys = [
    [<span class="hljs-string">'tableName'</span>, {keyProperty: {N: <span class="hljs-string">'0'</span>}}],
    [<span class="hljs-string">'tableName'</span>, {keyProperty: {N: <span class="hljs-string">'1'</span>}}],
    [<span class="hljs-string">'tableName'</span>, {keyProperty: {N: <span class="hljs-string">'2'</span>}}],
    <span class="hljs-comment">// etc., continuing to count up to</span>
    [<span class="hljs-string">'tableName'</span>, {keyProperty: {N: <span class="hljs-string">'1001'</span>}}],
];

<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> item of <span class="hljs-keyword">new</span> BatchGet(dynamoDb, keys)) {
    <span class="hljs-built_in">console</span>.log(item);
}
</code></pre>
				<p>The above code snippet will automatically split the provided keys into
					<code>BatchGetItem</code> requests of 100 or fewer keys, and any unprocessed keys will be
					automatically retried until they are handled. The above code will execute at
					least 11 <code>BatchGetItem</code> operations, dependening on how many items are returned
				without processing due to insufficient provisioned read capacity.</p>
				<p>Each item yielded in the <code>for...await...of</code> loop will be a single DynamoDB
					record. Iteration will stop once each key has been retrieved or an error has
				been encountered.</p>
				<h3 id="writing-batches-of-items">Writing batches of items</h3>
				<p>Create a <code>BatchWrite</code> object, supplying an instantiated DynamoDB client from the
					AWS SDK for JavaScript and an iterable of write requests that you wish to
					execute. The iterable may be synchronous (such as an array) or asynchronous
					(such as an object stream wrapped with <a href="https://github.com/calvinmetcalf/async-iter-stream">async-iter-stream</a>&#39;s
				<code>wrap</code> method).</p>
				<p>Each write request should contain either a <code>DeleteRequest</code> key or a <code>PutRequest</code>
				key as described <a href="http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_WriteRequest.html#DDB-Type-WriteRequest-DeleteRequest">in the Amazon DynamoDB API reference</a>.</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> { BatchWrite } <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-batch-iterator'</span>;
<span class="hljs-keyword">import</span> DynamoDB = <span class="hljs-built_in">require</span>(<span class="hljs-string">'aws-sdk/clients/dynamodb'</span>);

<span class="hljs-keyword">const</span> dynamoDb = <span class="hljs-keyword">new</span> DynamoDB({region: <span class="hljs-string">'us-west-2'</span>});
<span class="hljs-keyword">const</span> keys = [
    [<span class="hljs-string">'tableName'</span>, {DeleteRequest: {Key: {keyProperty: {N: <span class="hljs-string">'0'</span>}}}}],
    [<span class="hljs-string">'tableName'</span>, {PutRequest: {Item: {keyProperty: {N: <span class="hljs-string">'1'</span>}, otherProperty: {BOOL: <span class="hljs-literal">false</span>}}}}],
    [<span class="hljs-string">'tableName'</span>, {DeleteRequest: {Key: {keyProperty: {N: <span class="hljs-string">'2'</span>}}}}],
    [<span class="hljs-string">'tableName'</span>, {PutRequest: {Item: {keyProperty: {N: <span class="hljs-string">'3'</span>}, otherProperty: {BOOL: <span class="hljs-literal">false</span>}}}}],
    [<span class="hljs-string">'tableName'</span>, {N: <span class="hljs-string">'2'</span>}],
    <span class="hljs-comment">// etc., continuing to count up to</span>
    [<span class="hljs-string">'tableName'</span>, {DeleteRequest: {Key: {keyProperty: {N: <span class="hljs-string">'102'</span>}}}}],
];

<span class="hljs-keyword">for</span> <span class="hljs-keyword">await</span> (<span class="hljs-keyword">const</span> item of <span class="hljs-keyword">new</span> BatchGet(dynamoDb, keys)) {
    <span class="hljs-built_in">console</span>.log(item);
}
</code></pre>
				<p>The above code snippet will automatically split the provided keys into
					<code>BatchWriteItem</code> requests of 25 or fewer write request objects, and any
					unprocessed request objects will be automatically retried until they are
					handled. The above code will execute at least 5 <code>BatchWriteItem</code> operations,
					dependening on how many items are returned without processing due to
				insufficient provisioned write capacity.</p>
				<p>Each item yielded in the <code>for...await...of</code> loop will be a single write request
					that has succeeded. Iteration will stop once each request has been handled or an
				error has been encountered.</p>
			</div>
		</div>
		<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
			<nav class="tsd-navigation primary">
				<ul>
					<li class="globals  ">
						<a href="globals.html"><em>Globals</em></a>
					</li>
				</ul>
			</nav>
			<nav class="tsd-navigation secondary menu-sticky">
				<ul class="before-current">
					<li class=" tsd-kind-class">
						<a href="classes/batchget.html" class="tsd-kind-icon">Batch<wbr>Get</a>
					</li>
					<li class=" tsd-kind-class tsd-has-type-parameter">
						<a href="classes/batchoperation.html" class="tsd-kind-icon">Batch<wbr>Operation</a>
					</li>
					<li class=" tsd-kind-class">
						<a href="classes/batchwrite.html" class="tsd-kind-icon">Batch<wbr>Write</a>
					</li>
					<li class=" tsd-kind-interface">
						<a href="interfaces/batchgetoptions.html" class="tsd-kind-icon">Batch<wbr>Get<wbr>Options</a>
					</li>
					<li class=" tsd-kind-interface tsd-has-type-parameter">
						<a href="interfaces/batchstate.html" class="tsd-kind-icon">Batch<wbr>State</a>
					</li>
					<li class=" tsd-kind-interface">
						<a href="interfaces/pertableoptions.html" class="tsd-kind-icon">Per<wbr>Table<wbr>Options</a>
					</li>
					<li class=" tsd-kind-interface">
						<a href="interfaces/tableoptions.html" class="tsd-kind-icon">Table<wbr>Options</a>
					</li>
					<li class=" tsd-kind-interface tsd-has-type-parameter">
						<a href="interfaces/tablestate.html" class="tsd-kind-icon">Table<wbr>State</a>
					</li>
					<li class=" tsd-kind-interface tsd-has-type-parameter">
						<a href="interfaces/tablethrottlingtracker.html" class="tsd-kind-icon">Table<wbr>Throttling<wbr>Tracker</a>
					</li>
					<li class=" tsd-kind-interface tsd-has-type-parameter">
						<a href="interfaces/throttledtableconfiguration.html" class="tsd-kind-icon">Throttled<wbr>Table<wbr>Configuration</a>
					</li>
					<li class=" tsd-kind-type-alias tsd-has-type-parameter">
						<a href="globals.html#syncorasynciterable" class="tsd-kind-icon">Sync<wbr>OrAsync<wbr>Iterable</a>
					</li>
					<li class=" tsd-kind-type-alias">
						<a href="globals.html#tablestateelement" class="tsd-kind-icon">Table<wbr>State<wbr>Element</a>
					</li>
					<li class=" tsd-kind-type-alias">
						<a href="globals.html#writerequest" class="tsd-kind-icon">Write<wbr>Request</a>
					</li>
					<li class=" tsd-kind-variable">
						<a href="globals.html#max_read_batch_size" class="tsd-kind-icon">MAX_<wbr>READ_<wbr>BATCH_<wbr>SIZE</a>
					</li>
					<li class=" tsd-kind-variable">
						<a href="globals.html#max_write_batch_size" class="tsd-kind-icon">MAX_<wbr>WRITE_<wbr>BATCH_<wbr>SIZE</a>
					</li>
					<li class=" tsd-kind-function">
						<a href="globals.html#itemidentifier" class="tsd-kind-icon">item<wbr>Identifier</a>
					</li>
				</ul>
			</nav>
		</div>
	</div>
</div>
<footer>
	<div class="container">
		<h2>Legend</h2>
		<div class="tsd-legend-group">
			<ul class="tsd-legend">
				<li class="tsd-kind-module"><span class="tsd-kind-icon">Module</span></li>
				<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
				<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
				<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
				<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
				<li class="tsd-kind-index-signature"><span class="tsd-kind-icon">Index signature</span></li>
				<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
				<li class="tsd-kind-enum-member"><span class="tsd-kind-icon">Enumeration member</span></li>
				<li class="tsd-kind-property tsd-parent-kind-enum"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-enum"><span class="tsd-kind-icon">Method</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
				<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
				<li class="tsd-kind-constructor tsd-parent-kind-interface"><span class="tsd-kind-icon">Constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
				<li class="tsd-kind-index-signature tsd-parent-kind-interface"><span class="tsd-kind-icon">Index signature</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li>
				<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
				<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class"><span class="tsd-kind-icon">Accessor</span></li>
				<li class="tsd-kind-index-signature tsd-parent-kind-class"><span class="tsd-kind-icon">Index signature</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
				<li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
			</ul>
		</div>
	</div>
</footer>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
</body>
</html>